<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Coding Standard</title>
<meta name="author" content="Ion Yannopoulos, David Gay" />
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date: 2009-02-03 23:07:32 $
:version: $Revision: 1.9 $
:copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.
*/
body {
  font-family: Times;
  font-size: 16px;
}

.first {
  margin-top: 0 ! important }

.last {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dd {
  margin-bottom: 0.5em }

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning, div.admonition {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title,
div.admonition p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em }

div.footer, div.header {
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 0em 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1 {
  font-family: Arial, sans-serif;
  font-size: 20px;
}

h1.title {
 text-align: center;
 font-size: 32px;
}

h2 {
 font-size: 16px;
 font-family: Arial, sans-serif;
}

h2.subtitle {
  text-align: center }

h3 {
 font-size: 12px;
 font-family: Arial, sans-serif;
}

hr {
  width: 75% }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.line-block {
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee;
  border-color: #000000;
  border-width: thin; 
  font-size: 14px
}

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.option-argument {
  font-style: italic }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

table {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.citation {
  border-left: solid thin gray ;
  padding-left: 0.5ex }

table.docinfo {
  margin: 2em 4em;
}

table.footnote {
  border-left: solid thin black ;
  padding-left: 0.5ex }

td, th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

th.docinfo-name, th.field-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap;
  }

h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
  font-size: 100% }

tt {}

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="coding-standard">
<h1 class="title">Coding Standard</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">3</td>
</tr>
<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">TinyOS 2.0 Working Group</td>
</tr>
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Best Current Practice</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
<td>Draft</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>Ion Yannopoulos, David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">31-Dec-2004</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.5</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List &lt;tinyos-devel at mail.millennium.berkeley.edu&gt;</td>
</tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This document specifies a Best Current Practices for the
TinyOS Community, and requests discussion and suggestions for
improvements.  Distribution of this memo is unlimited.  This memo
is in full compliance with <a class="citation-reference" href="#tep-1" id="id1" name="id1">[TEP_1]</a>.</p>
</div>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#introduction" id="id7" name="id7">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference" href="#general-conventions" id="id8" name="id8">2&nbsp;&nbsp;&nbsp;General Conventions</a><ul class="auto-toc">
<li><a class="reference" href="#general" id="id9" name="id9">2.1&nbsp;&nbsp;&nbsp;General</a></li>
</ul>
</li>
<li><a class="reference" href="#packages" id="id10" name="id10">3&nbsp;&nbsp;&nbsp;Packages</a><ul class="auto-toc">
<li><a class="reference" href="#directory-structure" id="id11" name="id11">3.1&nbsp;&nbsp;&nbsp;Directory structure</a></li>
</ul>
</li>
<li><a class="reference" href="#language-conventions" id="id12" name="id12">4&nbsp;&nbsp;&nbsp;Language Conventions</a><ul class="auto-toc">
<li><a class="reference" href="#nesc-convention" id="id13" name="id13">4.1&nbsp;&nbsp;&nbsp;nesC convention</a><ul class="auto-toc">
<li><a class="reference" href="#names" id="id14" name="id14">4.1.1&nbsp;&nbsp;&nbsp;Names</a></li>
<li><a class="reference" href="#id5" id="id15" name="id15">4.1.2&nbsp;&nbsp;&nbsp;Packages</a></li>
<li><a class="reference" href="#preprocessor" id="id16" name="id16">4.1.3&nbsp;&nbsp;&nbsp;Preprocessor</a></li>
</ul>
</li>
<li><a class="reference" href="#c-convention" id="id17" name="id17">4.2&nbsp;&nbsp;&nbsp;C Convention</a></li>
<li><a class="reference" href="#java-convention" id="id18" name="id18">4.3&nbsp;&nbsp;&nbsp;Java convention</a></li>
<li><a class="reference" href="#other-languages" id="id19" name="id19">4.4&nbsp;&nbsp;&nbsp;Other languages</a></li>
</ul>
</li>
<li><a class="reference" href="#tinyos-conventions" id="id20" name="id20">5&nbsp;&nbsp;&nbsp;TinyOS Conventions</a><ul class="auto-toc">
<li><a class="reference" href="#error-returns" id="id21" name="id21">5.1&nbsp;&nbsp;&nbsp;Error returns</a></li>
<li><a class="reference" href="#passing-pointers-between-components" id="id22" name="id22">5.2&nbsp;&nbsp;&nbsp;Passing pointers between components</a></li>
<li><a class="reference" href="#usage-of-wiring-annotations" id="id23" name="id23">5.3&nbsp;&nbsp;&nbsp;Usage of wiring annotations</a></li>
</ul>
</li>
<li><a class="reference" href="#citations" id="id24" name="id24">6&nbsp;&nbsp;&nbsp;Citations</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id7" id="introduction" name="introduction">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
<dl class="docutils">
<dt>The purpose of a naming convention is twofold:</dt>
<dd><ul class="first last simple">
<li>To avoid collisions which prevent compilation or lead to errors.
In TinyOS the most important place to avoid such collisions is in
interface and component names.</li>
<li>To enable readers of the code to identify which names are grouped
together and which packages they are defined in.</li>
</ul>
</dd>
</dl>
<p>Remember that code that is useful will end up being read far more often
than it is written.  If you deviate from the suggestions or requirements
below, be consistent in how you do so.  If you add any new conventions to
your code, note it in a README.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id8" id="general-conventions" name="general-conventions">2&nbsp;&nbsp;&nbsp;General Conventions</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id9" id="general" name="general">2.1&nbsp;&nbsp;&nbsp;General</a></h2>
<blockquote>
<ul class="simple">
<li>Avoid the use of acronyms and abbreviations that are not well known.
Try not to abbreviate &quot;just because&quot;.</li>
<li>Acronyms should be capitalized (as in Java), i.e., Adc, not ADC.
Exception: 2-letter acronyms should be all caps (e.g., AM for active
messages, not Am)</li>
<li>If you need to abbreviate a word, do so consistently.  Try to be
consistent with code outside your own.</li>
<li>All code should be documented using <cite>nesdoc</cite> <a class="citation-reference" href="#nesdoc" id="id2" name="id2">[nesdoc]</a>, <cite>Doxygen</cite>
<a class="citation-reference" href="#doxygen" id="id3" name="id3">[Doxygen]</a> or <cite>Javadoc</cite> <a class="citation-reference" href="#javadoc" id="id4" name="id4">[Javadoc]</a>.  Ideally each command, event and
function has documentation.  At a bare minimum the interface, component,
class or file needs a paragraph of description.</li>
<li>If you write code for a file, add an <cite>&#64;author</cite> tag to the toplevel
documentation block.</li>
</ul>
</blockquote>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id10" id="packages" name="packages">3&nbsp;&nbsp;&nbsp;Packages</a></h1>
<p>For the purposes of this document a package is a collection of related
source and other files, in whatever languages are needed.  A package is
a logical grouping.  It may or may not correspond to a physical grouping
such as a single directory.  In TinyOS a package is most often a
directory with zero or more subdirectories.</p>
<p>nesC and C do not currently provide any package support, thus names
of types and components in different packages might accidentally
clash. To make this less likely, judiciously use prefixes on groups
of related files (often, but not always, part of a single package).
See the examples below.</p>
<p>In a package, we distinguish between public components (intended to
be used and wired outside the package) and private components (only
used and wired within the package). This distinction is not enforced
by nesC.</p>
<div class="section">
<h2><a class="toc-backref" href="#id11" id="directory-structure" name="directory-structure">3.1&nbsp;&nbsp;&nbsp;Directory structure</a></h2>
<blockquote>
<ul>
<li><p class="first">Each package should have it's own directory.  It may have as many
subdirectories as are necessary.</p>
</li>
<li><p class="first">The package's directory should match the package's prefix (if it
uses one), but in lower-case.</p>
</li>
<li><p class="first">The default packages in a TinyOS distribution are:</p>
<ul>
<li><dl class="first docutils">
<dt><cite>tos/system/</cite>.  Core TinyOS components.  This directory's</dt>
<dd><p class="first last">components are the ones necessary for TinyOS to actually run.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><cite>tos/interfaces/</cite>.  Core TinyOS interfaces, including</dt>
<dd><p class="first last">hardware-independent abstractions.  Expected to be heavily
used not just by <cite>tos/system</cite> but throughout all other code.
<cite>tos/interfaces</cite> should only contain interfaces named in TEPs.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><cite>tos/platforms/</cite>.  Contains code specific to mote platforms, but</dt>
<dd><p class="first last">chip-independent.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><cite>tos/chips/</cite>.  Contains code specific to particular chips and to</dt>
<dd><p class="first last">chips on particular platforms.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><cite>tos/libs/</cite>.  Contains interfaces and components which extend the</dt>
<dd><p class="first last">usefulness of TinyOS but which are not viewed as essential to its
operation.  Libraries will likely contain subdirectories.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><cite>apps/</cite>, <cite>apps/demos</cite>, <cite>apps/tests</cite>, <cite>apps/tutorials</cite>.  Contain</dt>
<dd><p class="first last">applications with some division by purpose.  Applications may
contain subdirectories.</p>
</dd>
</dl>
</li>
</ul>
</li>
<li><p class="first">It is not necessary that packages other than the core break up their
components and their interfaces.  The core should allow overrides of
components fairly easily however.</p>
</li>
<li><p class="first">Each directory should have a README describing its purpose.</p>
</li>
</ul>
</blockquote>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id12" id="language-conventions" name="language-conventions">4&nbsp;&nbsp;&nbsp;Language Conventions</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id13" id="nesc-convention" name="nesc-convention">4.1&nbsp;&nbsp;&nbsp;nesC convention</a></h2>
<div class="section">
<h3><a class="toc-backref" href="#id14" id="names" name="names">4.1.1&nbsp;&nbsp;&nbsp;Names</a></h3>
<blockquote>
<ul class="simple">
<li>All nesC files must have a <cite>.nc</cite> extension.  The nesC compiler requires
that the filename match the interface or component name.</li>
<li>Directory names should be lowercase.</li>
<li>Interface and component names should be mixed case, starting upper
case.</li>
<li>All public components should be suffixed with 'C'.</li>
<li>All private components should be suffixed with 'P'.</li>
<li>Avoid interfaces ending in 'C' or 'P'.</li>
<li>If an interface and component are related it is useful if they have
the same name except for the suffix of the component.</li>
<li>Commands, events, tasks and functions should be mixed case, starting
lower case.</li>
<li>Events which handle the second half of a split-phase operation begun
in a command should have names that are related to the commands.
Making the command past tense or appending <cite>'Done'</cite> are suggested.</li>
<li>Constants should be all upper case, words separated by underscores.
- Use of <cite>#define</cite> for integer constants is discouraged: use <cite>enum</cite>.</li>
<li>Type arguments to generic components and interfaces should use the
same case as C types: all lower-case separated by underscores, ending
in '_t'.</li>
<li>Module (global) variables should be mixed case, starting lower case.</li>
</ul>
</blockquote>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id15" id="id5" name="id5">4.1.2&nbsp;&nbsp;&nbsp;Packages</a></h3>
<blockquote>
<ul>
<li><p class="first">Each package may use a prefix for its component, interface and
global C names. These prefixes may sometimes be common to multiple
packages. Examples:</p>
<blockquote>
<ul class="simple">
<li>All hardware presentation layer names start with Hpl (this is
an example of a shared prefix).</li>
<li>Chip-specific hardware abstraction layer components and interfaces
start with the chip name, e.g., Atm128 for ATmega128.</li>
<li>The Maté virtual machine uses the Mate to prefix all its names.</li>
<li>Core TinyOS names (e.g., the timer components, the Init interface)
do not use a prefix.</li>
</ul>
</blockquote>
</li>
<li><p class="first">Some packages may use multiple prefixes. For instance, the ATmega128
chip package uses an Hpl prefix for hardware presentation layer
components and Atm128 for hardware abstraction layer components.</p>
</li>
</ul>
</blockquote>
</div>
<div class="section">
<h3><a class="toc-backref" href="#id16" id="preprocessor" name="preprocessor">4.1.3&nbsp;&nbsp;&nbsp;Preprocessor</a></h3>
<blockquote>
<ul class="simple">
<li>Don't use the nesC <cite>includes</cite> statement.  It does not handle macro
inclusion properly.  Use <cite>#include</cite> instead.</li>
<li>Macros declared in an <cite>.nc</cite> file must be <cite>#define</cite>'d after the
<cite>module</cite> or <cite>configuration</cite> keyword to actually limit their scope to
the module.</li>
<li>Macros which are meant for use in multiple <cite>.nc</cite> files should be
<cite>#define</cite>'d in a <cite>#include</cite>'d C header file.</li>
<li>Use of macros should be minimized:
<cite>#define</cite> should only be used where <cite>enum</cite> and <cite>inline</cite> do not suffice.<ul>
<li>Arguments to <cite>unique()</cite> should be <cite>#define</cite> string constants rather
than strings.  This minimizes nasty bugs from typos the compiler
can't catch.</li>
</ul>
</li>
</ul>
</blockquote>
</div>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id17" id="c-convention" name="c-convention">4.2&nbsp;&nbsp;&nbsp;C Convention</a></h2>
<blockquote>
<ul class="simple">
<li>All C files have a .h (header) or (rarely) a .c (source) extension.<ul>
<li>Filenames associated with a component should have the same name as
the component.</li>
<li>Filenames of a package should have a name with the package
prefix (if any).</li>
<li>Filenames which are not associated with a component should be lowercase.</li>
</ul>
</li>
<li>C does not protect names in any way. If a package uses a prefix, it
should also use it for all types, tags, functions, variables,
constants and macros. This leads naturally to:<ul>
<li>Minimize C code outside of nesC files.  In particular: most uses of
hardware specific macros in TinyOS 1.x should be replaced with nesC
components in TinyOS 2.x.</li>
</ul>
</li>
<li>C type names (define with <cite>typedef</cite>) should be lower case, words
separated by underscores and ending in <cite>'_t'</cite>.</li>
<li>C tag names (for <cite>struct</cite>, <cite>union</cite>, or <cite>enum</cite>) should be lower case,
words separated by underscores.  Types with tag names should provide
a typedef.</li>
<li>C types which represent opaque pointers (for use in parameters) should
be named similar to other types but should end in <cite>'_ptr_t'</cite>.</li>
<li>Functions should be lower case, words separated by underscores.</li>
<li>Function macros (<cite>#define</cite> ) should be all upper case, words separated
by underscores.<ul>
<li>Using function macros is discouraged: use <cite>inline</cite> functions.</li>
</ul>
</li>
<li>Constants should be all upper case, words separated by underscores.
- Use of <cite>#define</cite> for integer constants is discouraged: use <cite>enum</cite>.</li>
<li>Global variables should be mixed case, starting lower case.</li>
</ul>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id18" id="java-convention" name="java-convention">4.3&nbsp;&nbsp;&nbsp;Java convention</a></h2>
<blockquote>
<ul class="simple">
<li>The standard Java coding convention <a class="citation-reference" href="#java-coding-convention" id="id6" name="id6">[Java_Coding_Convention]</a>
should be followed.</li>
<li>All core TinyOS code is in the package <cite>net.tinyos</cite>.</li>
</ul>
</blockquote>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id19" id="other-languages" name="other-languages">4.4&nbsp;&nbsp;&nbsp;Other languages</a></h2>
<blockquote>
<ul class="simple">
<li>No established conventions.</li>
</ul>
</blockquote>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id20" id="tinyos-conventions" name="tinyos-conventions">5&nbsp;&nbsp;&nbsp;TinyOS Conventions</a></h1>
<p>TinyOS also follows a number of higher-level programming conventions,
mostly designed to provide a consistent &quot;look&quot; to TinyOS interfaces and
components, and to increase software reliability.</p>
<div class="section">
<h2><a class="toc-backref" href="#id21" id="error-returns" name="error-returns">5.1&nbsp;&nbsp;&nbsp;Error returns</a></h2>
<p>TinyOS defines a standard error return type, <tt class="docutils literal"><span class="pre">error_t</span></tt>, similar to Unix's
error returns, except that error codes are positive:</p>
<pre class="literal-block">
enum {
  SUCCESS        = 0,
  FAIL           = 1,
  ESIZE          = 2, // Parameter passed in was too big.
  ...
};
</pre>
<p><tt class="docutils literal"><span class="pre">SUCCESS</span></tt> represents successful execution of an operation, and <tt class="docutils literal"><span class="pre">FAIL</span></tt>
represents some undescribed failure. Operations can also return more
descriptive failure results using one of the Exxx constants, see the
<tt class="docutils literal"><span class="pre">tos/types/TinyError.h</span></tt> file for the current list of errors.</p>
<p>The <tt class="docutils literal"><span class="pre">error_t</span></tt> type has a combining function to support multiple wiring
of commands or events retuning <tt class="docutils literal"><span class="pre">error_t</span></tt>, defined as follows:</p>
<pre class="literal-block">
error_t ecombine(error_t r1, error_t r2) { return r1 == r2 ? r1 : FAIL; }
</pre>
<p>This function returns <tt class="docutils literal"><span class="pre">SUCCESS</span></tt> if both error returns are <tt class="docutils literal"><span class="pre">SUCCESS</span></tt>, an
error code if they both return the same error, and <tt class="docutils literal"><span class="pre">FAIL</span></tt> otherwise.</p>
<p>Commands that initiate a split-phase operation SHOULD return <tt class="docutils literal"><span class="pre">error_t</span></tt> if
the operation may be refused (i.e., the split-phase event may not be
signaled under some conditions). With such functions, the split-phase event
will be signaled iff the split-phase command returns <tt class="docutils literal"><span class="pre">SUCCESS</span></tt>.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id22" id="passing-pointers-between-components" name="passing-pointers-between-components">5.2&nbsp;&nbsp;&nbsp;Passing pointers between components</a></h2>
<p>Sharing data across components can easily lead to bugs such as data races,
overwriting data, etc. To minimise the likelyhood of these occurrences,
we discourage the use of pointers in TinyOS interfaces.</p>
<p>However, there are circumstances where pointers are necessary for
efficiency or convenience, for instance when receiving messages, reading
data from a flash chip, returning multiple results, etc.  Thus we allow the
use of pointers within interfaces as long as use of those pointers follows
an &quot;ownership&quot; model: at any time, only one component may refer to the
object referenced by the pointer. We distinguish two cases:</p>
<ul>
<li><p class="first">Ownership transferred for the duration of a call: in the following command:</p>
<pre class="literal-block">
command void getSomething(uint16_t *value1, uint32_t *value2);
</pre>
<p>we are using pointers to return multiple results. The component
implementing getSomething MAY read/write <tt class="docutils literal"><span class="pre">*value1</span></tt> or <tt class="docutils literal"><span class="pre">*value2</span></tt>
during the call and MUST NOT access these pointers after getSomething
returns.</p>
</li>
<li><p class="first">Permanent ownership transfer: in the following split-phase interface:</p>
<pre class="literal-block">
interface Send {
  command void send(message_t *PASS msg);
  event void sendDone(message_t *PASS msg);
}
</pre>
<p>components calling send or signaling <tt class="docutils literal"><span class="pre">sendDone</span></tt> relinquish ownership of
the message buffer. For example, take a program where component A uses
the <tt class="docutils literal"><span class="pre">Send</span></tt> interface and B provides it. If A calls <tt class="docutils literal"><span class="pre">send</span></tt> with a
pointer to <tt class="docutils literal"><span class="pre">message_t</span></tt> <em>x</em>, then ownership of <em>x</em> passes to B and A
MUST NOT access <em>x</em> while B MAY access <em>x</em>. Later, when B signals the
<tt class="docutils literal"><span class="pre">sendDone</span></tt> event with a pointer to <em>x</em> as parameter, ownership of <em>x</em>
returns to A and A MAY access <em>x</em>, while B MUST NOT access <em>x</em>.</p>
<p>If an interface with <tt class="docutils literal"><span class="pre">PASS</span></tt> parameters has a return type of
<tt class="docutils literal"><span class="pre">error_t</span></tt>, then ownership is transferred iff the result is
<tt class="docutils literal"><span class="pre">SUCCESS</span></tt>. For instance, in</p>
<pre class="literal-block">
interface ESend {
  command error_t esend(message_t *PASS msg);
  event void esendDone(message_t *PASS msg, error_t sendResult);
}
</pre>
<p>ownership is transferred only if <tt class="docutils literal"><span class="pre">esend</span></tt> returns <tt class="docutils literal"><span class="pre">SUCCESS</span></tt>, while
ownership is always transferred with <tt class="docutils literal"><span class="pre">esendDone</span></tt>. This convention
matches the rule for signaling split-phase completion events discussed
above.</p>
<p><tt class="docutils literal"><span class="pre">PASS</span></tt> is a do-nothing macro defined as follows:</p>
<pre class="literal-block">
#define PASS
</pre>
</li>
</ul>
<p>In the future, some tool may check that programs respect these ownership
transfer rules.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id23" id="usage-of-wiring-annotations" name="usage-of-wiring-annotations">5.3&nbsp;&nbsp;&nbsp;Usage of wiring annotations</a></h2>
<p>TinyOS checks constraints on a program's wiring graph specified by
annotations on a component's interfaces. Wiring constraints are specified
by placing <tt class="docutils literal"><span class="pre">&#64;atmostonce()</span></tt>, <tt class="docutils literal"><span class="pre">&#64;atleastonce()</span></tt> and <tt class="docutils literal"><span class="pre">&#64;exactlyonce()</span></tt>
attributes on the relevant interfaces. For instance, writing</p>
<pre class="literal-block">
module Fun {
  provides interface Init &#64;atleastonce();
...
</pre>
<p>ensures that programs using module <tt class="docutils literal"><span class="pre">Fun</span></tt> must wire its <tt class="docutils literal"><span class="pre">Init</span></tt> interface
at least once.</p>
<p>The <tt class="docutils literal"><span class="pre">&#64;atleastonce()</span></tt> and <tt class="docutils literal"><span class="pre">&#64;exactlyonce()</span></tt> annotations SHOULD be used
sparingly, as they can easily prevent modularising subsystem
implementations, which is undesirable. However, the <tt class="docutils literal"><span class="pre">&#64;atleastonce()</span></tt>
annotation SHOULD be used on initialisation interfaces (typically, the
<tt class="docutils literal"><span class="pre">Init</span></tt> interface) in modules, to prevent the common bug of forgetting to
wire initialisation code.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id24" id="citations" name="citations">6&nbsp;&nbsp;&nbsp;Citations</a></h1>
<table class="docutils citation" frame="void" id="tep-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="tep-1">[TEP_1]</a></td><td>TEP 1
&lt;<a class="reference" href="http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-1.html">http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-1.html</a>&gt;</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="tep-2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="tep-2">[TEP_2]</a></td><td>TEP 2
&lt;<a class="reference" href="http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-2.html">http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-2.html</a>&gt;</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="doxygen" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3" name="doxygen">[Doxygen]</a></td><td>Doxygen &lt;<a class="reference" href="http://www.doxygen.org">http://www.doxygen.org</a>&gt;</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="java-coding-convention" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id6" name="java-coding-convention">[Java_Coding_Convention]</a></td><td>Java Coding Convention
&lt;<a class="reference" href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html</a>&gt;</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="javadoc" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4" name="javadoc">[JavaDoc]</a></td><td>JavaDoc &lt;<a class="reference" href="http://java.sun.com/j2se/javadoc">http://java.sun.com/j2se/javadoc</a>&gt;</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="nesdoc" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2" name="nesdoc">[nesdoc]</a></td><td>nesdoc &lt;<a class="reference" href="http://www.tinyos.net/tinyos-1.x/doc/nesc/nesdoc.html">http://www.tinyos.net/tinyos-1.x/doc/nesc/nesdoc.html</a>&gt;</td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
